Ereignisse

Call Recording sendet zwei Ereignisse („FpEvents") auf dem anlageninternen Ereignisbus der Fluxpunkt-Module: StartRecordingEvent beim Start jeder Aufzeichnung und TranscriptionEvent nach Abschluss einer Transkription — Letzteres mit dem vollständigen Transkriptionstext in der Nutzlast. Typische Konsumenten sind EventBridge (Weiterleitung als Webhook, E-Mail, Syslog oder Datenbankeintrag) sowie eigene STARFACE-Module, die Ereignisse direkt abonnieren.

Verwendung durch Dritte

Diese Schnittstelle ist für die Nutzung durch Drittsysteme freigegeben. Änderungen und Erweiterungen werden je Version in den Release Notes dokumentiert.

Grundlagen

Typ: FpEvents — der modulübergreifende Ereignismechanismus der Fluxpunkt-Module auf dem anlageninternen Ereignisbus. Es handelt sich um keine Netzwerkschnittstelle: Ereignisse sind nur innerhalb der Anlage erreichbar; nach außen gelangen sie über EventBridge.
Identifikator: der Ereignisname StartRecordingEvent bzw. TranscriptionEvent. Die Namen sind anlagenweit gültig und unabhängig vom Namen der Modulkonfiguration. In EventBridge erscheinen die Ereignisse unter der Quelle de.fluxpunkt.fpevent (Kategorie FLUXPUNKT).
Nutzlast: ein JSON-Objekt. Felder ohne Wert (null) entfallen in der Nutzlast; unbekannte Felder werden beim Empfang ignoriert.
Zugriff: EventBridge abonniert Ereignisse per Konfiguration. Eigene Module verwenden die Modulfunktionen FpEvent abonnieren / FpEvent abbestellen (FpRegisterEvents/FpUnregisterEvents) — Download und Anleitung im Artikel Schnittstellen & APIs.
Zustellung: Fire-and-forget ohne Empfangsbestätigung. Fehler in einem Konsumenten beeinflussen weder die Aufzeichnung noch andere Konsumenten.
Katalog: Der anlagenweite Ereigniskatalog wird in der Ereignisliste der EventBridge-Dokumentation geführt; die vollständige Feldreferenz der Call-Recording-Ereignisse folgt auf dieser Seite.

`StartRecordingEvent` — Aufzeichnung gestartet

Wird unmittelbar nach dem Start des Mitschnitts veröffentlicht — also nach Auswertung der Aufzeichnungseinstellung, etwaiger Ansagen und einer etwaigen Opt-In-/Opt-Out-Abfrage. Wird ein Anruf nicht aufgezeichnet (Ausnahmeliste, Opt-Out, kein Treffer in den Einstellungen), entsteht kein Ereignis. Je aufgezeichnetem Anruf wird genau ein Ereignis gesendet, auch wenn mehrere Speicherziele konfiguriert sind.

Feld	Typ	Bedeutung
`callId`	String	STARFACE-Call-UUID des Anrufs. Identisch mit dem Wert `CallId` in der Metadatendatei und der Spalte `callid` der Protokolltabelle.
`startTime`	Long	Startzeitpunkt der Aufzeichnung als Unix-Zeitstempel in Millisekunden. Zugleich der erste Bestandteil des Datei-Basisnamens.
`callerName`	String	Aufgelöster Name des Anrufers (leer, wenn keine Namensauflösung vorliegt).
`calleeName`	String	Derzeit nicht befüllt (immer leer).
`calleeAccountId`	Integer	Derzeit nicht befüllt (immer `0`).
`callerNumber`	String	Signalisierte Rufnummer des Anrufers.
`calledNumber`	String	Gerufene Nummer (bei internen Zielen die Durchwahl).
`callerAccountId`	Integer	Derzeit nicht befüllt (immer `0`).
`channel`	String	Asterisk-Kanalname des aufgezeichneten Kanals. Korrelationsschlüssel zum späteren `TranscriptionEvent`.
`instanceId`	String	UUID der Modulkonfiguration (Instanz), die die Aufzeichnung ausgelöst hat.
`incoming`	Boolean	`true` bei eingehenden, `false` bei ausgehenden Anrufen. Entspricht `in`/`out` in der Spalte `direction` der Protokolltabelle.

Beispiel: StartRecordingEvent
{
  "callId": "5e8f0f5a-1d24-4f6b-9c3a-7b2f9d4e8a11",
  "startTime": 1739948363496,
  "callerName": "Max Mustermann",
  "calleeName": "",
  "calleeAccountId": 0,
  "callerNumber": "004970222797821",
  "calledNumber": "31",
  "callerAccountId": 0,
  "channel": "SIP/2001-00000042",
  "instanceId": "5c9c8140-aaa8-40b4-9b9f-fdd686feb4f5",
  "incoming": true
}

`TranscriptionEvent` — Transkription abgeschlossen

Wird veröffentlicht, sobald eine Aufzeichnung transkribiert, in ein einheitliches Textformat konvertiert und abgelegt wurde. Voraussetzungen: In der Aufzeichnungseinstellung ist ein Transkriptionsprofil gewählt und die Option „Transkriptionen bereitstellen" aktiviert (siehe Konfiguration). Die Transkription läuft asynchron nach Gesprächsende; das Ereignis erscheint daher zeitversetzt — je nach Gesprächslänge und Transkriptionsprovider Sekunden bis Minuten nach dem Auflegen, in jedem Fall vor dem Upload in die Speicherziele.

Feld	Typ	Bedeutung
`startTime`	Long	Startzeitpunkt der zugrunde liegenden Aufzeichnung in Millisekunden — identisch mit `startTime` des `StartRecordingEvent` und dem Zeitstempel im Datei-Basisnamen.
`channel`	String	Asterisk-Kanalname der Aufzeichnung (aus der Metadatendatei). Korrelationsschlüssel zum `StartRecordingEvent`.
`transcriptionJson`	String	Vollständige Transkription im providerunabhängigen Einheitsformat — ein JSON-Objekt, das als String übergeben wird (JSON-in-String, siehe unten).
`rawTranscription`	String	Unveränderte Rohantwort des Transkriptionsproviders als JSON-String. Struktur providerabhängig; für Auswertungen `transcriptionJson` bevorzugen.
`service`	String	Verwendeter Transkriptionsprovider: `deepgram`, `starface-whisper`, `whisperx`, `openai-whisper` oder `elevenlabs`.
`instanceName`	String	Name der Modulkonfiguration, die die Transkription erstellt hat.
`calledNumber`	String	Gerufene Nummer (aus der Metadatendatei).
`callerNumber`	String	Rufnummer des Anrufers (aus der Metadatendatei).
`callerName`	String	Name des Anrufers (aus der Metadatendatei; entfällt, wenn unbekannt).
`voicemail`	Boolean	Unterscheidet Gesprächs- von Voicemail-Transkriptionen. Bei Ereignissen von Call Recording stets `false`.

Beispiel: TranscriptionEvent
{
  "startTime": 1739948363496,
  "channel": "SIP/2001-00000042",
  "transcriptionJson": "{\"time\":1739948363496,\"confidence\":0.96,\"paragraphs\":[{\"text\":\"Guten Tag, mein Name ist Mustermann …\",\"channel\":0,\"speaker\":0,\"start\":1.42,\"end\":6.87,\"confidence\":0.97}],\"source\":{\"provider\":\"deepgram\",\"model\":\"nova-2\",\"speakerLayout\":\"channel_per_side\"}}",
  "rawTranscription": "{ … providerabhängige Rohantwort … }",
  "service": "deepgram",
  "instanceName": "Call Recording",
  "calledNumber": "31",
  "callerNumber": "004970222797821",
  "callerName": "Max Mustermann",
  "voicemail": false
}

Struktur von `transcriptionJson`

transcriptionJson enthält — nach dem Dekodieren des Strings — ein JSON-Objekt mit folgender Struktur:

Feld	Typ	Bedeutung
`time`	Long	Startzeitpunkt der Aufzeichnung in Millisekunden (identisch mit `startTime`).
`confidence`	Float	Gesamtkonfidenz der Transkription (0–1).
`paragraphs`	Array	Gesprächsverlauf als Liste von Absätzen (siehe folgende Tabelle).
`source`	Objekt	Herkunft der Transkription; kann bei älteren Transkriptionen fehlen.
`source.provider`	String	Providertyp, z. B. `deepgram`.
`source.model`	String	Verwendetes Modell (kann fehlen).
`source.speakerLayout`	String	Interpretation von `channel`/`speaker`: `channel_per_side` (Kanal = Gesprächsseite: `0` = Anrufer, `1` = Angerufener), `channel_per_side_heuristic` (wie zuvor, aber heuristisch zugeordnet), `diarized` (`speaker` = Sprecherindex, `channel` nicht aussagekräftig) oder `single_speaker` (nur ein Sprecher).

Jeder Eintrag in paragraphs:

Feld	Typ	Bedeutung
`text`	String	Transkribierter Text des Absatzes.
`channel`	Integer	Audiokanal (Bedeutung gemäß `source.speakerLayout`).
`speaker`	Integer	Sprecherindex innerhalb des Kanals bzw. der Diarisierung.
`start`	Float	Beginn des Absatzes in Sekunden ab Aufzeichnungsstart.
`end`	Float	Ende des Absatzes in Sekunden ab Aufzeichnungsstart.
`confidence`	Float	Konfidenz des Absatzes (0–1).

transcriptionJson — dekodiert
{
  "time": 1739948363496,
  "confidence": 0.96,
  "paragraphs": [
    {
      "text": "Guten Tag, mein Name ist Mustermann, ich rufe wegen meiner Bestellung an.",
      "channel": 0,
      "speaker": 0,
      "start": 1.42,
      "end": 6.87,
      "confidence": 0.97
    },
    {
      "text": "Guten Tag Herr Mustermann, was kann ich für Sie tun?",
      "channel": 1,
      "speaker": 0,
      "start": 7.02,
      "end": 9.85,
      "confidence": 0.95
    }
  ],
  "source": {
    "provider": "deepgram",
    "model": "nova-2",
    "speakerLayout": "channel_per_side"
  }
}

Anwendungsbeispiel

Ein CRM-Anbieter abonniert TranscriptionEvent über EventBridge als Webhook. Sein Endpunkt dekodiert transcriptionJson, hängt den Gesprächsverlauf an den per callerNumber ermittelten Kundendatensatz an und nutzt startTime zur Zuordnung des Ruflisteneintrags — ohne Datenbankzugriff auf die Anlage.

Fehler-/Sonderfälle

Situation	Verhalten
Anruf wird nicht aufgezeichnet (Ausnahmeliste, Opt-Out, kein Treffer)	Kein `StartRecordingEvent`.
Option „Transkriptionen bereitstellen" deaktiviert	Die Transkriptionsdatei wird zwar erstellt und hochgeladen, aber es wird kein `TranscriptionEvent` gesendet.
Transkription schlägt fehl	Bis zu 3 Versuche (Wiederholung im 30-Sekunden-Takt der Nachverarbeitung); danach wird die Transkription verworfen — es gibt kein Fehlerereignis.
Metadatendatei nicht lesbar	`TranscriptionEvent` entfällt; die Ursache steht im Modul-Log.
`callerAccountId`, `calleeAccountId`, `calleeName` in `StartRecordingEvent`	Derzeit nicht befüllt (`0` bzw. leer); die Felder sind für künftige Erweiterungen reserviert.
`transcriptionJson`/`rawTranscription`	JSON-in-String: vor der Auswertung dekodieren. Bei Serialisierungsfehlern kann das jeweilige Feld fehlen.
`TranscriptionEvent` enthält keine Call-ID	Korrelation über `startTime` + `channel` mit dem vorangegangenen `StartRecordingEvent` (dieses enthält die `callId`).

Ein ausbleibendes Ereignis ist damit stets ein Hinweis, im Modul-Log nachzusehen.

Versionierung & Kompatibilität

Ereignisnamen und Feldnamen sind stabile Verträge; Erweiterungen erfolgen additiv (neue Ereignisse, neue optionale Felder). Verarbeiten Sie Nutzlasten daher tolerant gegenüber zusätzlichen Feldern. Den anlagenweiten Ereigniskatalog führt die Ereignisliste der EventBridge-Dokumentation; Änderungen dokumentieren die Release Notes der jeweiligen Modulversion.

Grundlagen​

StartRecordingEvent — Aufzeichnung gestartet​

TranscriptionEvent — Transkription abgeschlossen​

Struktur von transcriptionJson​

Fehler-/Sonderfälle​

Versionierung & Kompatibilität​